<?php

/**
 * 所有的Twitter、人人、豆瓣等的数据抓取的类都需要实现此接口。这样便可以通过统一的方法调用到信息，而不需要关系具体每个类里面的怎样得到数据的。
 * 每个实现类需要在类内部定义一个常量，内容为该服务的代号，例如Twitter就可以定为'twitter'，人人网就可以定为'renren'，具体语法可以是：const name = 'twitter';
 * 这在实现职责链模式时需要用到，下面的方法文档中会说明。
 * 
 * @author Clippit
 *
 */
interface IService {
	
	/**
	 * 构造函数，提供登录功能。两个参数可以是用户名/密码，也可以是用来OAuth的参数。
	 * 
	 * @param string $param1 第一个参数
	 * @param string $param2 第二个参数
	 */
	public function __construct($param1, $param2);

	/**
	 * 注册/绑定该服务时的验证或OAuth环节，由oauth控制器发起
	 * 对于OAuth绑定服务，即开始登录验证环节；对于普通验证的绑定服务，在这里传入需要的参数后立即进行验证
	 * 验证成功后，在OAuth服务的Callback URL中再次激活oauth控制器的save动作，将两个oauth_token和oauth_token_secret存入数据库
	 * 对于普通验证，成功后直接将用户名和加密后的密码存入数据库。
	 * 
	 */
	public static function register($param1 = NULL, $param2 = NULL);

	/**
	 * 获取当前用户在该服务上的Timeline内容（Tweets、新鲜事、广播等）。更新失败即抛出异常throw new Exception('xxx failed.')
	 * 
	 * @param int $count 每次返回的消息数，默认为10条
	 * @param int $page 返回第几页的内容
	 * 
	 * @return 一个包含了最新消息的二维数组，每条信息的数组元素定义如下：
	 *         array(
	 *               'uid'=>该user在该服务中的ID,
	 *               'id'=>该条信息在相应服务中的ID,
	 *               'source'=>'消息来源服务的代号',
	 *               'user'=>'用户名',
	 *               'avatar'=>'头像URL',
	 *               'content'=>消息正文内容,
	 *               'datetime'=>发布时间，格式为Unix时间戳（长整型）， 请参考strtotime函数
	 *         )
	 */
	public function getLatest($count = 10, $page = 0);

	/**
	 * 发布一条信息（Tweet，状态等）。发送失败即抛出异常throw new Exception('xxx update failed.');
	 * 
	 * @param string $target 消息发出去的目标 
	 * @param unknown_type $content
	 * 
	 */
	public function update($content);

	/**
	 * 回复一条消息。发送失败即抛出异常throw new Exception('xxx update failed.');
	 * 
	 * 这个方法在实现的时候要首先判断一下自己是否是相应的$target，不是就直接返回FALSE。例如：
	 * if ($target != self::name) return FALSE;
	 * 
	 * @param string $target 目标服务的代号（用于判断是否处理，见update方法说明）
	 * @param int $id 回复的消息ID
	 * @param string $content 回复的正文，如果相应的服务对字数有限制，需要做截断处理
	 * @param int $reply_to 回复给某人的UID（可选，似乎只有人人中用得到）
	 * 
	 * @return bool 消息回复是否成功
	 */
	public function reply($target, $id, $content, $reply_to = null);

	/**
	 * 获取单一用户的资料和更新消息。更新失败即抛出异常throw new Exception('xxx failed.');
	 * 
	 * @param string $target 目标服务的代号（用于判断是否处理，见reply方法说明）
	 * @param int $uid 用户在目标服务中的ID
	 * 
	 * @return 一个数组，定义如下：
	 *         array(
	 *             'profile'=>array(//一个数组，包含了一些有用的个人资料，必须要有的是名字、头像信息，其他的自由考虑，例如BIO、生日之类的
	 *                             'username'=>'用户名',
	 *                             'avatar'=>'头像URL（可以是稍微大一点的头像图片）'
	 *                        ),
	 *             'timeline'=>array(//包含了该特定用户最近的10条更新，格式和getLatest方法返回值相同
	 *                         )
	 *         )
	 */
	public function getProfile($target, $uid);
	
	/** 
	 * 获取当前登录用户的显示名称
	 *
	 * @return string 用户名
	 */
	public function getMyName();
	
	/**
	 * 获取当前登录用户的UID
	 *
	 * @return string UID
	 */
	public function getMyID();
}



?>